<HTML>
<TITLE>module moist_conv</TITLE>
<BODY BGCOLOR="#AABBCC" TEXT="#332211" >

<DIV ALIGN="CENTER"> <FONT SIZE=1>
<A HREF="#INTERFACE">PUBLIC INTERFACE</A> / 
<A HREF="#ROUTINES">ROUTINES</A> / 
<A HREF="#NAMELIST">NAMELIST</A> / 
<A HREF="#CHANGES">CHANGES</A> / 
<A HREF="#ERRORS">ERRORS</A> / 
<A HREF="#REFERENCES">REFERENCES</A> / 
<A HREF="#NOTES">NOTES</A> 
</FONT>
<BR><BR></DIV><HR>


<H2>module moist_conv</H2>
<A NAME="HEADER">
<PRE>
     <B>Contact:</B>
     <B>Reviewers:</B>

     <B><A HREF=".doc.log#moist_conv.f90">Tags/Status</A></B>
</PRE>
</A><!-- END HEADER -->
<!--------------------------------------------------------------------->
<A NAME="OVERVIEW">
<HR>
<H4>OVERVIEW</H4>
<!-- BEGIN OVERVIEW -->
<PRE>

    Computes moist convective adjustment and precipitation.

    Temperature and specific humidity adjustments are computed in
    model layers where the lapse rate and relative humidity exceed
    the moist adiabatic lapse rate and a threshold relative humidity.

</PRE>
</A><!-- END OVERVIEW -->
<!--------------------------------------------------------------------->
<A NAME="DESCRIPTION">
<!-- BEGIN DESCRIPTION -->
<PRE>
   The features include:

    1) multiple pass scheme (e-group version)
    2) convective detrainment option 
       (for use with the stratiform cloud scheme)
    3) energetically consistent adjustment with precipitation type

    Reference: Manabe, S., (1969). Mon. Wea. Rev. 97, 739-798.

</PRE>
</A><!-- END DESCRIPTION -->
<!--------------------------------------------------------------------->
<A NAME="MODULES_USED">
<HR>
<H4>OTHER MODULES USED</H4>
<!-- BEGIN MODULES_USED -->
<PRE>

     sat_vapor_pres_mod
          utilities_mod
          constants_mod

</PRE>
</A><!-- END MODULES_USED -->
<!--------------------------------------------------------------------->
<A NAME="INTERFACE">
<HR>
<H4>PUBLIC INTERFACE</H4>
<!-- BEGIN INTERFACE -->
<PRE>

use moist_conv_mod [, only: moist_conv_init, moist_conv ]

   moist_conv_init:  Initializes the module, namelist, and constants.
                     This routine may be called by the user, but does
                     not have to be (it will be done automatically).

   moist_conv:  Computes the moist convective adjustments for
                temperature and specific humidity; also optional 
                adjustments for liquid and ice cloud condensates.
                This routine also returns the mass of rain and snow
                that reach the ground, this is done in an energetically
                consistent way.

</PRE>
</A><!-- END INTERFACE -->
<!--------------------------------------------------------------------->
<A NAME="ROUTINES">
<HR>
<H4>PUBLIC ROUTINES</H4>
<!-- BEGIN ROUTINES -->
<PRE>

<b>call moist_conv_init</b> ( )

   There are no arguments.

--------------------------------------------------------

<b>call moist_conv</b> ( tin, qin, pfull, phalf, coldt, tdel, qdel, rain, snow,
                     [,lbot] [,cf] [,conv] [,qldel,qidel] )

  Input

      tin       temperature at full levels (deg k)
                  [real, dimension(:,:,nlev+1)]
 
      qin       specific humidity of water vapor at full levels
                  [real, dimension(:,:,nlev+1)]
 
      pfull     pressure at full levels in pascals
                  [real, dimension(:,:,nlev)]
 
      phalf     pressure at half levels in pascals
                  [real, dimension(:,:,nlev)]
 
      coldt     should MCA produce snow in this column?
                  [logical, dimension(:,:)]
 
  Output

      tdel      temperature adjustment (deg k)
                  [real, dimension(:,:,nlev)]
 
      qdel      specific humidity adjustment
                  [real, dimension(:,:,nlev)]
 
      rain      liquid precipitation, vertically integrated (kg/m2)
                  [real, dimension(:,:)]
 
      snow      ice phase precipitation, vertically integrated (kg/m2)
                  [real, dimension(:,:)]
  
  Input (Optional)

      lbot      Index of the lowest model level
                  [integer, dimension(:,:)]

      cf        stratiform cloud fraction (used only when operating with
                stratiform cloud scheme)   [real, dimension(:,:,nlev)]

  Output (Optional)

      conv      flag that specifies whether a particular model level was
                adjusted  [logical, dimension(:,:,nlev)]

      cfdel     change in stratiform cloud fraction
                  [real, dimension(:,:,nlev)]

      qldel     change in liquid water condensate due to convective detrainment
                (kg condensate /kg air)   [logical, dimension(:,:,nlev)]

      qidel     change in ice condensate due to convective detrainment
                (kg condensate /kg air)   [logical, dimension(:,:,nlev)]

  Notes:

   1) When operating with the stratiform cloud scheme, optional
      arguments cf, cfdel, qldel, and qidel should all be present
      for the convective detrainment option. The code only checks if
      cf is present.

</PRE>
</A><!-- END ROUTINES -->
<!--------------------------------------------------------------------->
<A NAME="NAMELIST">
<HR>
<H4>NAMELIST</H4>
<!-- BEGIN NAMELIST -->
<PRE>

<b>&moist_conv_nml</b>

   hc      Relative humidity criterion for moist convection only;
           where 0.0 <= hc <= 1.0   [real, default: hc=1.0]

   beta    fraction of convective condensation that is detrained
           into a stratiform cloud; where 0.0 <= beta <= 1.0
           (only applicable if the stratiform cloud scheme and
           tracers are turned on, optional argument cf must be present)
             [real, default: beta=0.0]

   tolmin  minimum tolerance (for unstable lapse rate)
             [real, default: tolmin=0.02]

   tolmax  maximum tolerance (for unstable lapse rate)
             [real, default: tolmax=0.10]

   itsmod  maximum number of iterations at the same tolerance
             [integer, default: itsmod=30]

</PRE>
</A><!-- END NAMELIST -->
<!--------------------------------------------------------------------->
<A NAME="CHANGES">
<HR>
<H4>CHANGE HISTORY</H4>
<!-- BEGIN CHANGES -->
<PRE>
<B><A HREF=".doc.log#moist_conv.f90">Revision history</A></B>

<b>Prior changes</b>

     MPP version created. Minor changes for open_file, error_mesg,
     and Fortran write statements. Answers should reproduce the
     previous version.

<b>Prior changes</b>

  * logical input argument added that specifies whether frozen
    precipitation should be computed for the column
    (note: the adjustment is now done energetically consistent
     for the type of precip)

  * output arguments for column integrated rain and snow replace
    the argument for total precip

  * optional arguments added for stratiform cloud fraction (input) and
    change in stratiform cloud fraction (output), this makes the code
    consistent with a new version of the stratiform cloud scheme

</PRE>
</A><!-- END CHANGES -->
<!--------------------------------------------------------------------->
<A NAME="ERRORS">
<HR>
<H4>ERROR MESSAGES</H4>
<!-- BEGIN ERRORS -->
<PRE>

<b>Warning in moist_conv</b>

    <b>maximum iterations reached</b>
        The maximum number of iterations were reached. 
        Increase the maximum number of iterations (itsmod) or
        the maximum tolerance (tolmax).

</PRE>
</A><!-- END ERRORS -->
<!--------------------------------------------------------------------->
<A NAME="REFERENCES">
<HR>
<H4>REFERENCES</H4>
<!-- BEGIN REFERENCES -->
<PRE>

     Manabe, S., (1969). Mon. Wea. Rev. 97, 739-798.

</PRE>
</A><!-- END REFERENCES -->
<!--------------------------------------------------------------------->
<A NAME="BUGS">
<HR>
<H4>KNOWN BUGS</H4>
<!-- BEGIN BUGS -->
<PRE>

     None.

</PRE>
</A><!-- END BUGS -->
<!--------------------------------------------------------------------->
<A NAME="NOTES">
<HR>
<H4>NOTES</H4>
<!-- BEGIN NOTES -->
<PRE>

     None.

</PRE>
</A><!-- END NOTES -->
<!--------------------------------------------------------------------->
<A NAME="PLANS">
<HR>
<H4>FUTURE PLANS</H4>
<!-- BEGIN PLANS -->
<PRE>

     None.

</PRE>
</A><!-- END PLANS -->
<!--------------------------------------------------------------------->

<HR>
</BODY>
</HTML>
